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Abstract 

We present the system for versioning two packages: the TAUOLA of r-lepton de- 
cay and PHOTOS for radiative corrections in decays. The following features can be 
chosen in an automatic or semi-automatic way: (1) format of the common block 
HEPEVT; (2) version of the physics input (for TAUOLA): as published, as initialized by 
the CLEO collaboration, as initialized by the ALEPH collaboration (it is suggested 
to use this version only with the help of the collaboration advice), new optional 
parametrizations of matrix elements in 4ir decay channels; (3) type of application: 
stand-alone, universal interface based on the information stored in the HEPEVT com- 
mon block including longitudinal spin effects in the elementary Z/7* — > t + t~ pro- 
cess, extended version of the standard universal interface including full spin effects 
in the H/A — > t + t~ decay, interface for KKMC Monte Carlo, (4) random number 
generators; (5) compiler options. 

To be submitted to Comput. Phys. Commun. 
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PROGRAM SUMMARY 



Title of the environment: tauola-photos-F, release II. 
Computer: PC running GNU/Linux operating system 

Programming languages and tools used: CPP: standard C-language preprocessor, 

GNU Make builder tool, also FORTRAN-77 compiler. 

Size of the package: 10 MB uncompressed, 

2 MB packed for distribution into tar.gz archive. 

Keywords: 

particle physics, Monte Carlo methods, tau decays, TAUOLA [1], PHOTOS [2] 
Nature of the physical problem: 

The code of Monte Carlo generators often has to be tuned to the needs of large HEP 
Collaborations and experiments. Usually, these modifications do not introduce important 
changes in the algorithm, but rather modify the initialization and form of the hadronic 
current in r decays. The format of the event record (HEPEVT common block) used to 
exchange information between building blocks of Monte Carlo systems often needs modi- 
fication. Thus, there is a need to maintain various, slightly modified versions of the same 
code. The package presented here allows the production of ready-to-compile versions 
of TAUOLA [1] and PHOTOS [2] Monte Carlo generators with appropriate demonstration 
programs. 

The new algorithm, universal interface of TAUOLA to work with the HEPEVT common 
block is also documented here. Finally minor technical improvements of TAUOLA and 
PHOTOS are also listed. 
Method of solution: 

The standard UNIX tool: the C-language preprocessor is used to produce a ready-to- 
distribute version of TAUOLA [1] and PHOTOS [2] code. The final version of F0RTAN77 code 
is produced from the library of 'pre-code' that is included in the package. 
Typical running time: 

Depends on the speed of the computer used and the demonstration program chosen. 

Typically a few seconds. 

Accessibility: 



web page: http://cern.ch/wasm/goodies.html 

References: 

• 'The tau decay library TAUOLA: Version 2.4' P 

• 'PHOTOS: A Universal Monte Carlo for QED radiative corrections. Version 2.0" [2j 
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1 Introduction 



The TAUOLA jUllUE] and PHOTOS [5JI2] programs are computing projects that have a rather 
long history. Written and maintained by well defined authors, they nonetheless migrated 
into a wide range of applications where they became ingredients of complicated simulation 
chains. As a consequence, a large number of different versions are currently in use. From 
the algorithmic point of view, they often differ only in a few small details, but incorporate 
substantial amount of specific results from the distinct r-lepton measurements. The 
difference in the versions of the programs used is often due to the specific requirements of 
the interfaces to other packages in the simulation chain (for instance, the format of the 
event record has to be adjusted). 

The present utility for constructing specific versions of TAUOLA and PHOTOS is prepared 
for software librarians and advanced users. The idea was to create a repository which 
allows them to include and keep main options of TAUOLA developed for different purposes. 
At the same time, the repository can provide the standard FORTRAN files, which can 
be handled later in the same way as the published versions of the packages. The other, 
relatively new project, which we will call TAUOLA universal interface, is also discussed 
here. 

Our present document is not aimed to be the manual of the PHOTOS and TAUOLA pack- 
ages. It is assumed that the user is familiar with the programs themselves and their 
documentation, see Refs. OEldlHlEj . The purpose of the paper is to document how all 
parts of the code, including different versions and options, are combined into one distri- 
bution package. Minor improvements in the codes, since the time of publication, are also 
listed here. The paper is an extended and enlarged version of the earlier documentation [S] 
and supersedes it. 

Motivations for versioning: 

1. PHOTOS: Diferent versions of the Fortran code are necessary according to the differ- 
ent versions of the HEPEVT common block being in use in the HEP libraries (sin- 
gle/double precisions, dimension of matrices). 

2. TAUOLA: Different versions of Fortran code are motivated by: (A) different versions 
of initialization of physics parameters; (B) interfaces with different Monte Carlo 
generators for the production of r lepton(s); and (C) different versions of the HEPEVT 
common block: 

• (A) Different physics initializations: 

(1) As published in £Q, with improvements from Ref. [7j; 

(2) As initialized by ALEPH collaboration [S] (it is suggested to use this version 
only after asking the collaboration for advice); 

(3) As initialized by CLEO collaboration [Oj (see printout of this version for 
details) ; 

(4) New parallel 4ir channels of r decay based on Novosibirsk data [TP] . 

(5) New parallel 4ir channels of r decay based on Refs. [TH ITj. 

• (B) Different interfaces with MC generators: 

(1) Old demo program as in published version £Q; 
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(2) Interface to KKMC [12!; 

(3) New universal interface using HEPEVT common block including spin effects 
in the elementary Z/^y* — > t + t~ process |13j . 

(4) The extended version of the standard universal interface including trans- 
verse spin effects in the H/A — > t + t~ decay P^lfTSlfTUlfTTj . 

• (C) Different versions of the HEPEVT common block. 

3. TAUOLA and PHOTOS: different versions of random number generators. 

4. TAUOLA and PHOTOS: makefile's with different compiler flags. 

The aim is to provide full backward compatibility at the level of the Fortran source 
with the various versions being at present in use. Standard Unix tools and infrastructure 
are used in the discussed setup: cpp the C-language preprocessor; its #if , #elif and 
#include directives, as well as symbolic links and cat command. It is expected that 
the user will employ this setup to create her/his version of TAUOLA and PHOTOS libraries 
(subdirectories tauola/ and photos/) and that other subdirectories of the setup will be 
erased/stored separately. 

2 Organization of the directory tree 

Once unpacked, the main directory TAUOLA is created. 
It contains README file and: 

subdirectories including Fortran precode 

1. photos-F/: Main directory containing PHOTOS precode with options. 

2. tauola-F/: Main directory containing TAUOLA precode with options. 

3. tauola-f actory/: Directory containing the glue program, which prepares the non- 
standard directory tauola-F/. 

4. demo-factory/: Directory for updating the input in demo files. For specialized use 
only, see Section l2~3l 

5. randg/: Directory containing random number generators, which are kept separately 
from the rest of TAUOLA and PHOTOS source code. This should facilitate the replace- 
ment with the versions of random number generators favoured by the user. Random 
number generators are kept in Fortran subroutines placed in files photos-random. h 
and tauola-random.h. 

6. include/: Directory containing the HEPEVT-xxx.h files for different versions of the 
HEPEVT common block. The symbolic link HEPEVT. h to the one actually used will 
be placed in this directory at the time of initialization. The phyfix.xxx files with 
versions of Fortran subroutine PHYFIX used only by TAUOLA universal interface 
are also stored there. The version to be used needs to be copied into phyf ix.h; for 
more details, see README-phyf ix. 
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subdirectories necessary to run demo and 
to install packages on different platforms 

1. glibk/: Directory containing histogramming package, used by demos only. 

2. jetset/: Directory containing JETSET MC package, used by demos only. 

3. jetset2/: Directory containing PYTHIA MC package, used by demos only. 

4. eli/: Directory containing files necessary to construct demo to be run with PYTHIA 
MC package. 

5. platform/: Directory containing system-dependent versions of make.inc files for 
supported platforms. 

6. make.inc: Symbolic link to the chosen make-xxxx . inc located in subdirectory 
platform/. The make-xxxx . inc files define machine- dependent flags for compilers 
etc. to be used by all makefiles. 

The following directories are created 
once the actions of the setup are completed: 

1. photos/: Standard directory with Fortran code of PHOTOS library and its demo. 

2. tauola/: Standard directory with Fortran code of TAUOLA library, its demos and 
example outputs. 

(a) tauola/demo-standalone: Demo program for TAUOLA executed in a stan- 
dalone mode. 

(b) tauola/demo- jetset: Demo program for TAUOLA executed with universal 
interface and physics event generators using the HEPEVT common block. In 
this demo HEPEVT is filled by JETSET74 ^H] Monte Carlo event generator. 

(c) tauola/demo-pythia: Optionally, a demo program for TAUOLA executed with 
universal interface and HEPEVT common block filled by PYTHIA ^Hj Monte 
Carlo event generator can be created as well. 

(d) tauola/demo-KK-f ace: Interface to KK Monte Carlo [T2*] . 
2.1 Options for PHOTOS Monte Carlo 

The different options of PHOTOS that can be created, correspond solely to the different 
versions of the HEPEVT common block. The possible options are: 

1. KK-all - for KK Monte Carlo, older versions 

2. 2kD-all - arrays dimension 2000, double precision 

3. 4kD-all - arrays dimension 4000, double precision 
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4. 2kR-all - arrays dimension 2000, single precision 

5. lOkD-all - arrays dimension 10000, double precision 

The action of preparing the required version of the library is performed with the help 
of cpp preprocessor. It creates a file photos. f from precode stored in photos. F. Once 
this is done, the symbolic link to the required version of the HEPEVT common block is 
defined. This link is used in the construction of the tauola library, see next section. 

2.2 Options for TAUOLA Monte Carlo 

Basic options for physics initializations are: cpc; cleo; aleph. As results of the action 
performed by the package: 

1. The tauola/ subdirectory is erased; 

2. The directory structure of tauola/ is rebuilt; 

• the tauola/ directory is filled with the Fortran code, libraries and makefiles; 

• tauola/demo-xx are filled with the Fortran code of demos; 

The three possible versions of created tauola. f correspond to formfactors and branch- 
ing ratios defined respectively as in: (cpc) published version of TAUOLA pJEj; (aleph) 
as adopted by ALEPH collaboration [E], (cleo) as adopted by CLEO collaboration [H]. 

Remarks: 

• The makefile files are prepared to run TAUOLA within the environment of the distri- 
bution TAUOLA directory; however the templates for makefiles are compatible with those 
of the KK Monte Carlo. Thus if the tauola directory is copied into its respective place in 
the KKMC distribution tree, and make makf lag of KK/ff bench/ is executed, it overwrites 
the makefile file in tauola/. The new ones are produced from makefile .tempi and 
match the KKMC structure. 

• Additional parametrizations for formfactors, which can be useful in some applica- 
tions, are stored in the directory TAUOLA/tauola-F/suppl. They are not ready to use 
and some cross-checks are mandatory. At present, the code used in Refs. [THj and [20] is 
stored there. 

2.3 How to change the setting of TAUOLA input parameters 

It is often necessary to change some of the TAUOLA input parameters, such as branching ra- 
tios, mass of the r-lepton, etc. It is convenient to have it done once for all applications, i.e. 
demo-KK-f ace, demo-jetset and demo-standalone. The purpose of the demo-factory 
directory is exactly that. Here one can create the .F files for the interfaces, by the set of 
'Paste' commands embodied in the script klej, out of the blocks of Fortran code. More 
precisely the following files can be re-created: 
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• For demo-KK-f ace: ./prod/Tauf ace.F 

• For demo- jetset: . /prod/tauola_photos_ini . F 

• For demo -standalone: . /prod/taumain.F 

For details of the intialization routines, which are semi-identical in the three cases, see 
Refs. jSllHC]. This requires special care from the physics point of view. In many cases, 
the input parameters are inter-related with the actual choice of form factors. The changes 
should thus be performed consistently. 

How to proceed: 

1. Some of the routines in directory . /source have to be updated by hand first. They 
are stored in individual files. The ones that usually should not be modified are 
write-protected. 

2. Later execution of the script klej will create the following files from the pieces 
stored in the directory ./source simply by pasting them together: 

• . /prod/Tauf ace .F, 

• . /prod/tauola_photos_ini . F, 

• ./prod/taumain.F. 

Automatic check (using diff) with the archive versions stored in the directory 
. /back will also be executed. 

3. Finally the following commands copy the files into the appropriate places: 

(a) cp prod/Tauf ace .F . . /tauola-F/tauf ace-KK-F/Tauf ace . F 

(b) cp prod/tauola_photos_ini . F . . /tauola-F/jetset-F/tauola_photos_ini . F 

(c) cp prod/taumain.F . ./tauola-F/standalone-F/taumain.F 

2.4 Random number generators 

• PHOTOS and TAUOLA have their own copies of the random number generators. They 
are contained in the include files placed in the directory randg. 

• The user who wants to implement her/his own generators, e.g. compatible with the 
ones used by the collaboration, should replace the files: 

— . /photos-random. h, 

— ./tauola-random.h 

by those including the appropriate wrappers of his/her own random generators (or 
empty files if the generators of the same name reside elsewhere) . 
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2.5 Compiler flags, etc. 



Platform-dependent parts of the makefiles are stored in the directory platform/. At 
present options are available for various distributions of the Linux platform only, but it 
is rather straightforward to extend them to the new ones. 

3 Universal interface with HEPEVT common block 

In the present section, we shall document for the first time, how to install and use the 
TAUOLA universal interface with 'any' production generator, to include spin effects 
in e.g. the Z/^y* — > t + t~ process [T3*|ll4j . The approximate spin correlations are calculated 
from the information stored in the HEPEVT common block j2I] filled by 'any' r production 
program. As a demonstration example it is interfaced with the JETSET generator; however, 
it works in the same manner with PYTHIA, HERWIG and should work with the ISA JET 
generator as well. In fact, such an interface can be considered as a separate software 
project, to some degree independent from both the specific problem of r production and 
its decay. The aim of this interface is not to replace the matrix element calculations, 
but rather to provide a method of calculating/ estimating spin effects in cases when these 
would not be taken into account at all. 

3.1 HEPEVT common block and HEPEVT event record 

The question of adapting the universal interface 1 to different versions of an HEPEVT event 
record goes beyond the technicalities discussed in Section |2~T1 In fact it is quite involved, 
as it depends on specific needs due to the way the HEPEVT event record is actually coded 
into the HEPEVT common block. It varies from application to application according to the 
physics requirement. During the MC4LHC Workshop [22] these issues were discussed and it 
was found, thanks to interaction with the users, that the TAUOLA universal interface 
works with all 3 basic options for HEPEVT filled by PYTHIA 6.2 (MSTP(128)=0 , 1 , 2), as 
well as with HERWIG (6.150) [23] . in our example we keep only the working interface 
with PYTHIA version 5.7, the working example with other installations can be found e.g. 
in |23. 

The discussion of the related problems go beyond this document; we refer the reader 
to Section |H] for more details. We are also convinced that the problems, because they 
originate from physics, will appear in event records in other programming languages such 
as C++. 

3.2 Longitudinal spin effects 

Let us start with the simpler case, when only longitudinal spin degrees are included. Then 
the interface acts in the following way: 

• The user has to verify if the r lepton is forced to be stable in the package performing 
generation of the r production. 

1 The question is even more serious in the case of PHOTOS. 
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• The contents of the HEPEVT common block is searched for all r leptons and r neu- 
trinos. 

• It is checked if there are r flavour pairs (two r leptons or a r lepton and a r neutrino) 
originating from the same mother (s). 

• The decays of the r flavour pairs are performed with the subroutine TAUOLA. Lon- 
gitudinal spin correlations are generated in the case of the r produced from the 
decay of: W — > tu, Zj^f* — > tt, and the charged Higgs boson H ± — > tv (for the 
neutral Higgs boson the full spin correlations are used, see Section fo.4|) . Parallel 
or antiparallel spin configurations are generated, before calling on the r decay, and 
then the decays of 100% polarized r's are executed. 

• In the case of the Higgs boson (for the spin correlations to be generated) the identifier 
of the r mother must be that of the Higgs boson. The particle code convention as 
that used by the PYTHIA 5 . 7 [23] Monte Carlo is adopted, but it can be changed 
by the user, as explained later in this section. 

• In the case of the W and Z/j*, this is not necessary, because the interface assumes 
these production mechanisms as defaults, even if the W or Z/^* bosons are not 
explicitly present in the event record. For example if from the same mother as that 
of the r, a v T is also produced, the W (of the momentum equal to the sum of r and 
u T ) will be taken as the true mother of the r. Similarly, if another r with opposite 
charge is produced from the same mother, the Z/^y* is assumed to be the mother of 
the r pair. 

• The spin effects in the states of r + , r~ produced from explicit or implicit Z/'y* states 
are upgraded up to nearly KORALZ standards Po^ lTF] . If bremsstrahlung protons are 
present in the event record (as sisters of Z), then they have to be mergerd either 
with beams or with r's, accordingly to approximation explained in ^Hj. Photon 
radiation in the decay is performed with PHOTOS package [SlEj- 

Let us note that the calculation of the r polarization created from the Z and/or virtual 7* 
(as a function of the direction) represents a rather non-trivial extension if high precision 
is required. Generally, the dedicated study of the production matrix elements of the host 
generator is necessary in every individual case. The method applied here is based on 
approximations [llflll"4"| . 

3.3 Organization of the interface 

The TAUOLA interface is organized in a modular form to be used conveniently in 'any 
environment'. 

Initialization 

Initialization is performed with the CALL TAUOLA (MODE , KEYSPIN) , M0DE=-1. All nec- 
essary input is directly coded in the subroutine TAUOLA placed in a file tauf ace-jetset . f . 
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The following input parameters are set at this call. We omit those, which are standard 
input for TAUOLA as defined in its documentation. They are hard-coded in the subroutine. 



Parameter 


Meaning 


POL 


Internal switch for spin effects in r decays and only for the lon- 
gitudinal case. Normally the user should set P0L=1.0, and when 
P0L=0.0 spin polarization effects are absent. 


KrHIGGb (.6) 


(KF=25, 35, 36) Flavour code for h, H and A 


KrHluUn 


(KF=37) Flavour code for H + 


T/T?7A 

J\rZ.U 


[i\.r=z,o) r lavour cofle tor Z 


Kr GAM 


(KF=22) Flavour code for 7 


KFTAU 


(KF=15) Flavour code for t~ 


KFNUE 


(KF=16) Flavour code for v T 


xmtau 


r-lepton mass, used only for KFHIGGSC3), see Section EOl 


xmh 


Higgs boson mass, used only for KFHIGGS(3) 


psi 


Mixing scalar-pseudoscalar angle, this angle is used only for Higgs 
boson with flavour code equal KFHIGGS(3) 



Event generation 

For every event generated by the production generator, all r leptons will decay with 
the single CALL TAUOLA (0,KEYSPIN) (KEYSPIN=l/0 denotes spin effects switched on/off). 
In its execution, all r leptons will be first localized, their positions stored in internal 
common block TAUPOS, and the information necessary for calculating the r spin state 
will be read from HEPEVT common block. The spin state for the given r (or r pair) will 
be generated later, and finally the decay of the polarized r will be performed with the 
standard TAUOLA action. In particular, the decay products of r will be boosted to the 
laboratory frame and added to the complete event configuration stored in the HEPEVT 
common block. 

Calculation of the r spin state 
Once CALL TAUOLA (0,KEYSPIN) is executed and r leptons are found, the spin states 
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have to be calculated. 

First, we look in HEPEVT for the position of r's mothers and store them in matrix 
IM0THER(20). Each mother giving r lepton(s) is stored only once, independently of the 
number of produced r's. Later, for every IMOTHER(i) we execute the following steps: 

1. The daughters, which are either r leptons or u T , are searched for. 

2. The daughters are combined in pairs, and the case of more than 1 pair is not expected 
to be important; ad hoc pairing is then performed. 

3. The two main cases are thus (r r) or (r v T ). 

4. The default choices in these two main cases are, respectively, Z/'-f* or W, unless 
the identifier of IMOTHER(i) is different and explicitly defined, e.g. as a neutral (or 
charged) Higgs boson. 

5. Calculation of the spin parameters is independent from kinematic variables and 
straightforward in all cases except Z/'-f* (see |13j). 

6. For Z/^*, the polarization function Pz fSj is calculated with the help of the function 
PLZAPX(H0PE,IM0,NP1,NP2). The HOPE is the logical parameter defined in subrou- 
tine TAUOLA placed in the file tauf ace-jetset .f . It tells whether spin effects can 
be calculated or not. If available information is incomplete, HOPE is set to .false. . 
Then PLZAPX(HOPE, IMO ,NP1 ,NP2) returns 0.5. The IMO denotes the position of the 
r mother in HEPEVT common block, the MP1 denotes the position of r + and the NP2 
denotes the position of r~. 

7. To calculate the reduced 2^2 body kinematical variables s and cos#, the sub- 
routine ANGULlKPDl ,PD2,Q1,Q2,C0STHE) is used. Four-momenta of the incoming 
effective beams and outgoing r + and r~ are denoted by PD1, PD2, Qi, Q2, respectively. 
The variables s and cos 9 are then used in the function Pz- 

Run summary 

After the series of events is generated the optional CALL TAUOLA (1 ,KEYSPIN) can be 
executed. The information on the whole sample, such as the number of generated r 
decays, branching ratios calculated from matrix elements, etc. will be printed. 

Demonstration program 

Our main program demo.f is stored in the subdirectory demo-jetset. It reads in the 
file init.dat, which includes some input parameters for the particular run, such as the 
number of events to be generated (by JETSET/PYTHIA), or the type of the interaction it 
should use to produce r's. We address the reader directly to the code for more details. It 
is self-explanatory. The printouts at the interface initialization has the form presented in 
Fig. Q while that at the end of the execution has the form presented in Fig. |21 
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* *****TAUOLA UNIVERSAL INTERFACE: ****** * 

* *****VERSIDN 1.10, November 2003 ****** * 

* ** AUTHORS : P. Golonka, B. Kersevan, *** * 

* **T. Pierzchala, E. Richter-Was, ****** * 

* ****** 2. Was, M. Worek *************** * 

* **USEFUL DISCUSSIONS, IN PARTICULAR *** * 

* *WITH C. Biscarat and S. Slabospitzky** * 

* ****** are warmly acknowledged ******** * 

* * 

* ********** INITIALIZATION ************ * 

* 1.00000 tau polarization switch must be 1 or * 

* 1.57080 Higs scalar /pseudo mix CERN-TH/2003-166 * 



Figure 1: Printout of TAU0LA universal interface initialization 



* *****TAU0LA UNIVERSAL INTERFACE: ****** * 

* *****VERSI0N 1.10, November 2003 ****** * 

* **AUTH0RS: P. Golonka, B. Kersevan, *** * 

* **T. Pierzchala, E. Richter-Was, ****** * 

* ****** 2. Was, M. Worek *************** * 

* **USEFUL DISCUSSIONS, IN PARTICULAR *** * 

* *WITH C. Biscarat and S. Slabospitzky** * 

* ****** are warmly acknowledged ******** * 

* ****** END OF MODULE OPERATION ******** * 



Figure 2: Printout of TAU0LA universal interface end-of-run messages 



12 



3.4 Transverse spin effects 

The extended version of the standard universal interface, of the TAUOLA r-lepton de- 
cay library, includes the complete spin effects for r leptons originating from the spin zero 
particle, i.e. in H/A — > t + t - decay [T3l[T21[TB] . As usual, the interface is expected to 
work with any Monte Carlo generator providing production (and subsequent decay into 
pair of t leptons) of the Higgs boson. Since the Higgs boson spin is zero, the spin corre- 
lations of its decay products do not depend at all on the mechanism of the Higgs boson 
production. Technical difficulties related to the choice of r + and r~ spin quantization 
frames, present in the case of e + e~ — > Z/'-f* — > t + t~ |2*%l l2TI] (initial state bremsstrahlung 
effects included or not), are not present. The analytical form of the density matrix is sim- 
ple. To calculate the density matrix for the pair of r-leptons it is thus enough to: know 
their four-momenta, know that they indeed originate from the Higgs boson, and assume 
the type of the Yukawa interaction. Such information is stored in the HEPEVT common 
block [2T] used by practically all Monte Carlo generators for Higgs boson production. 

The interface acts in the following way and according to principles described in |3]: 

• The algorithm is organized in two steps. In the first step, the r lepton pair is 
generated and the r leptons decay in their respective rest frames, as if there were 
no spin effects at all. In the second step, the spin weight is calculated and rejection 
is performed. If the event is rejected, only the generation of the r lepton decays is 
repeated. 

• The spin weight for Higgs boson decay into r + r~ is given by the following formula 

1 3 3 

i=l 3=1 



The components of the density matrix R^ are equal i? 33 = — 1, Rn = ±1, R 2 2 = ±1, 
respectively, for pure scalar and pseudoscalar Higgs boson, and all other components 
are zero. The h l and h? are the polarimetric vectors of the leptons (they are 
calculated by TAUOLA) . 

In general, the Yukawa coupling can be written as f(a + itry^T. With our choice 
of quantization frames, the following non-zero components of Rij are obtained (see 
Ref. HZ|): 

R - 1 R -R ~ ^ R - R - 2abP (2) 



/ 4 2 

where (3 — wl — With Yukawa coupling written in the form fA r (cos0 + 

isin07 5 )r and with the limit — > 1, the expressions reduce to the components of 
the rotation matrix by an angle —20: 

R11 = R22 = cos 20, R 12 = —R 2 i = sin 2(f). (3) 
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The following changes had to be introduced to the algorithm explained in Ref. 

• The quantization frames for the spin states of r + and r~ need to be properly oriented 
with respect to each other. In our solution they are simply connected by the boost 
along the r lepton momenta as defined in the Higgs boson rest frame. At the 
technical level this is enforced by the TRALOR routine [3], which defines the relation 
of the spin quantization frames with the laboratory frame. As an intermediate 
step this routine uses the Higgs boson rest frame. 

• The density matrix for the pure scalar /pseudoscalar case was taken from Ref. [SU] . 
and in the most general case in Ref. (B^- We have adapted it to the quantization 
frames as specified previously. Two cases are implemented: pure scalar Higgs boson 
and Higgs boson with mixed scalar-pseudoscalar coupling. 

• Generation of r + and r~ decays is implemented in the subroutine SPINHIGGS placed 
in the file tauf ace-jetset . f and performed following the method explained and 
used in Refs. 0123 • 

• The function wthiggs (IFPSEUDO ,HH1 ,HH2) is used to calculate the spin weight. The 
HH1 and HH2 are the r + and r _ polarimetric vectors calculated inside the subroutine 
DEKAY placed in the file tauola.f. The IFPSEUDO is a logical parameter, defined in 
the subroutine TAUOLA and placed in the file tauf ace-jetset . f. It tells whether 
spin effects are calculated for the scalar or for the mixed scalar-pseudoscalar Higgs 
boson. If we have pure scalar Higgs boson it is set to .false.. If we have mixed 
scalar-pseudoscalar case it is set to . true . . The pure pseudoscalar case is for = |. 

• We have assumed that production generator provides two-body Higgs boson decays 
to r leptons. In particular, that it does not provide any bremsstrahlung corrections. 
Instead, PHOTOS [5112] (see also can be used for that purpose, once the generation 
of decays is completed. 

• A more complete inclusion of bremsstrahlung corrections would require a substantial 
rewriting and extension of the program to the solution presented in Ref. J2| o r a 
similar one. 

4 How to use the package 

1. Start with make Clean from main directory to secure against mismatches. 

2. Check platform-dependent makefiles. 

• Go to subdirectory platform/ 

• Determine if make-xxx . inc file specific for your computer is present there: for 
Linux it is make-linux. inc; for others it needs to be adapted. 

• Erase the symbolic link make . inc which exists in this directory and create a 
new one, which points at the chosen make-xxx. inc: 
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— rm make . inc 

— for Linux: In -s make-linux . inc make. inc 

Afterwards check whether a link to the make . inc is present in the main direc- 
tory. 

3. The settings of TAUOLA input parameters can be changed for all implemented appli- 
cations, see Section l2~3l for details. 

4. PHOTOS and TAUOLA have their own private random generators. If you wish to replace 
them, you should do it at this point, see Section ITU 

5. Create required versions of photos/ and tauola/ directories. It is mandatory to 
create photos/ directory first, i.e. before creating tauola/. 

• Go to the directory photos-F 

• Type one of the following commands to choose the required version of HEPEVT: 

— make KK-all 

— make 2kD-all 

— make 4kD-all 

— make 2kR-all 

— make lOkD-all 

• Go to directory tauola-F: 

• Type one of the following commands to choose the required version of TAUOLA 
initialization: 

— make cpc 

— make cleo 

— make aleph 

The user can then type 

— make pythia 

to construct the additional demo executable with PYTHIA. In this demonstra- 
tion program, old PYTHIA version 5.720 [TH] is used. The user is anyway ex- 
pected to attach the package to a new software, up to date at the time of 
installation. In this example, the matching of the common block dimensions is 
not automatically assured. The option make 4kD-all has to be used. 

6. The required version of PHOTOS and TAUOLA will reside in newly (re) created directo- 
ries ./photos and ./tauola. 

7. The following demos can be invoked from those directories: 

• Demo for PHOTOS resides in ./photos/demo, and can be invoked by command 
make followed by make run. 
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• Demo for TAUOLA stand-alone resides in 

. /tauo la/demo -standalone, and can be invoked by the command make fol- 
lowed by make run. 

• Demo for TAUOLA with JETSET being a host Monte Carlo resides in 

. /tauola/demo-jetset, and can be invoked by the command make followed 
by make run. 

• Demo for TAUOLA with PYTHIA being a host Monte Carlo resides in 

. /tauola/demo-pythia, and can be invoked by the command make followed 
by make run. 

• Interface to KKMC resides in . /tauola/KK-f ace/Tauf ace . f . It has to be moved 
to ./KK2f/Tauface.f of distribution directory of KKMC [EJ. The rest of the 
./tauola directory should replace the original one of the KK Monte Carlo 
distribution. 

Finally, let us remark that most of the TAUOLA tree is not necessary and can be erased at 
this point. Code and makefiles of the directories . /tauola and . /photos are sufficient. To 
execute demo programs, the directories . / j etset and . /glibk need to be kept or replaced 
by the appropriate links. The make . inc symbolic link pointing to the make-xxxx . inc 
file in the directory ./platform also needs to be kept. The file make-xxxx . inc defines 
appropriate compiler flags. 

5 New hadronic currents for r — > An channels of r 
decay 

The parametrization of formfactors developed for 4ir channels of r decay and based 
on Novosibirsk data has been coded in a form suitable for the TAUOLA Monte Carlo 
package ^U]. There exist two 47r final states in r~ decay ( i.e. — > z/ r 7r - 7r 7r°7r°, 
t~ —* i/ T 7r - 7r - 7r + 7r°). Both are available as parallel decay modes in the cpc, cleo or 
aleph versions. To get the new 4tt channels of r decay (BINP version) one should act in 
the following way: 

1. Go to directory tauola-f actory. 

• There is a glue programme that prepares a Fortran 'precode' of TAUOLA library 
and places it in the directory . ./tauola-F. 

• Type the following command to see the parameters of the glue programme: 

— ./glue 

• Type the following command to choose the BINP version: 

— ./glue binp 

• Type the following command to come back to the standard version: 

— ./glue standard 
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2. Go to the main directory. 

3. Act according to the instructions described in the previous chapter. 

4. The required TAUOLA version (cpc, cleo or aleph) with new 4ir channels of r decay 
(BINP version) will reside in newly (re)created directory ./tauola. 

Another parametrization of form factors for Am channels based on References [TT|l7j is 
available as well. It can be installed, similar the case described above. The only difference 
is that flag binp has to be replaced with Karlsruhe. 

6 Universal tool for HEP Monte Carlo generator com- 
parison: MC-TESTER 

Within the scope of the TAUOLA-PHOTOS project work, a pilot project of MC-TESTER tool 
for semi-automatic comparisons of Monte Carlo generators has been deployed. Initially, 
the project was targeted to be a part of this package: it was intended to be used as a 
debugging/ analysis tool for comparing the results produced by various versions of TAUOLA 
and PHOTOS code. 

We decided however to publish MC-TESTER as an independent project [23] • The scope 
of its possible use spans far beyond its original use case. We have however preserved the 
relationship between the two projects: we include two versions of TAUOLA code (that may 
be produced using TAUOLA-PHOTOS ) in the MC-TESTER distribution (versions 1.0 and 1.1) 
as a test that verifies the correctness of MC-TESTER installation. 

More information and the code of MC-TESTER is available from its web page . 

7 Minor upgrades in TAUOLA and PHOTOS 

There is no need to publish the new versions of the programs: since the last publication, 
the upgrades are minor. Nonetheless let us list here the main improvements collected over 
the years. The list of fixes for numerically rather insignificant bugs, as well as necessary 
changes due to the evolution of compilers, will not be given here. For that purpose we refer 
the reader to the comments in the code, to the README files included in the distribution 
and to the package web page 

7.1 TAUOLA 

Apart from the modifications listed in Section 1, no changes were introduced in the 
cpc and aleph initializations of TAUOLA since the time they became available. In the 
case of cleo initialization, a change was introduced in the r — > z/7r + 7r + 7r~7r° channel; 
normalization of the u current was adjusted to experimental data To this end, the 
to contribution was diminished from 68% down to 40% of the total rate for the r — > 
V7T + 7i + 7i~ it channel. The new version of TAUOLA 2.7, was nonetheless introduced, which 
is marked in all initialization printouts, to document progress in bug fixing etc. The 
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creation dates printed in the outputs are retained. They mark the time when the bulk of 
the work was done. 

Since publication a careful analysis of a hadronic current for Air final states was 
performed; related extensive studies and comparisons are documented in Ref. [37] . The 
new parametrization based on Refs. [TTllTj was also installed in TAUOLA . Different options 
of models discussed in Ref. [TH] were probed. Let us list changes with respect to [TOj . 
which are now installed in the TAUOLA code if used with the binp option. We will use the 
opportunity to list misprints found in Ref. [TOj as well: 

1. In Table 4 of Ref. fU] m all columns of function arguments, \[Q 2 were listed rather 
than Q 2 , as written in the table header. 

2. Formula (20) of [TQj should read g a (s) = (1 — 4m 2 /s) 1 / 2 , rather than g a (s) = 
(s - Am 2 /sfl 2 . 

3. All propagators derived from formula (18) of Ref. ^Uj, should be normalized to —1 
at q 2 = 0; also imaginary part should be set to zero below opening of the appropriate 
decay channel (i.e. typically for q 2 < Am 2 ). 

4. In the definition of the p propagator in formula (18) of Ref. ^U], the term dm(q 2 ) 
was neglected. The full p propagator should read 



D p (q Z 



dm(q 2 ) 



q i _ m 2 - M p T p dm(q 2 ) + %M p Y p 



9 P (M 2 ) 



(h p (q 2 ) - h p (M 2 ) - (q 2 - Af 



dh p (q 2 



dq 2 



q*=M* 



/g P (M 2 p ), 



where 



1 4m 2 j n | _ 



(q — 4m 2 ) 



h P (q 2 ) = { 







for q 2 > 4m 2 , 
for q 2 = GeV 2 
otherwise . 



(4) 



(5) 



5. The full oj propagator should read (the 9 (?J\ was approximated by 1): 



DM 2 



9uj{M 2 ) 



(6) 



1 + 17.560( v /g 2 - M u ) + 141.110( v /g 2 - MJ 2 + 
, +894.884( v^ 2 - M u f + 4977.35( v /g 2 - M w ) 4 + 
+7610.66( v^ 2 " - Mjf - 42524.4^^ - MJ 6 



-1333.26 + 4860.19^ - 6000.81( ^/q 2 ) 2 + 2504.97^ 



2^3 



for vr < 1.0 GeV, 



otherwise . 



(7) 
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Function (J2J) is involved, because of effects due to three-body phase space, threshold 
effects of pion masses as well as opening of the resonant p channel in u decay. 



6. In formula (16) of Ref. ^H] the overall sign was missing. 

7. In formula (21) of Ref. ^U], the coefficient in front of the second line should include 
s instead of a. 

8. We have recalculated, using two methods, the outcome from formula (21) of [TU]. We 
have found some numerical difference with respect to the one used before. The size 
of the difference is small, except the region above 1.3 GeV, which is not important 
anyway (see Ref. |3Tj). 

9. In the comment for formula (21) of Ref. ^Uj it should be stated that three-vectors 
and energies are defined in the a\ (3ir) system rather than in the p (4tt) system. 

10. In formula (25) of Ref. [TOj, the overall coefficient z m i x was missing, but it was set 
in the code to z mix = 1 anyway. 

11. At the beginning of Section 5 in Ref. ^U] the numerical constant A 2 = 1.2 GeV 
should be defined, rather than A alone. 

All points from the above list do not change the numerical content of the code, except 
for point |Hl which brings a modification, and consequently leads to numerically small 
compensating changes of the content of the tables of functions G presented in Ref. |l()j . 

We found, while playing with different versions of the TAUOLA code describing the 
Novosibirsk hadronic current, that we had for some time an overall sign error in the 
space-like component of the current. For all distributions involving pions only, it was 
fully compensated by the choice of the fit functions G(Q 2 ) (formulae (14), (15) and (22- 
24) of Ref. POj)- Also all figures in Ref. ^H] are correct. 

However, as a consequence of the bug, the distributions involving u T were affected in 
TAUOLA BINP. The effect was not large enough for comparisons with TAUOLA CLEO to hint 
for the problem. The differences were within the expected systematic errors of the two 
parametrizations. We have also found an additional misprint in the numerical value for 
our fit functions: G^+^-^+^o, G^ +7T _ n+n0 and G^+^o^o^o (see Table 4, Ref. [ID])- An overall 
constant or function was missing. Once corrections are taken together, the values in Table 
4 should be multiplied respectively by: 



76.565 a/0.71709* 




(8) 




for the G". 



■+ 



7T 



(9) 
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96.867 |z_formal(Q 2 ) I J0.70907* ^/Q 1 - 0.26413 

— -= for the G 7r + 7T o n o 7r o(Q 2 ) (10) 



before being used in formulae (14), (15) and (22-24) of Ref. [TO]. Numerical values of the 
|z_f ormal(Q 2 )| function are tabulated in the new TAUOLA function ZFA1TAB(Q2), as was 
the case with the functions G. 

Finally, during the work, as a byproduct, we have switched on the interference between 
the u and non-a> parts of this current. This changed the overall rate, mainly because of the 
interference of small, spread over all phase space tails of the uj Breit-Wigner propagator. 
The numerical effect is not visible in the differential distribution, but it affects the total 
rate by 1.017(1). We changed the normalization of G n + n - T + n o(Q 2 ) and G" +w - n+JT o(Q 2 ) 
by the same factor, so as to reproduce the total An rate as in PDG 2000. Note that the 
interference of the uj current with the remaining part provides 1.7 % effect on the total 
rate. 



The changes we introduced are collected in the following subsections. 
7.2.1 Subroutine PHCORK 

During the test phase of the Photos+ jHH|, a C++ implementation of the PHOTOS algo- 
rithm, it turned out that the generation becomes unstable for events produced at TeV 
energies. The use of PHOTOS at this energy range was then studied for the first time. The 
kinematics of events produced by PYTHIA 5.7 was often not precise enough, because of 
rounding errors for (REAL*4) floating-point variables. 

The particles described by a tree-structured event record (i.e. HEPEVT common block 
used by PHOTOS), form decay 'branches' composed of a 'mother' - the decaying particle, 
and 'daughters' - its decay products. When the kinematics of a branch is not correct (the 
sum of 4-momentum of decay products does not match the 4-momentum of the mother 
particle or the particles momenta are off shell), numerical instabilities are encountered. 
It is not possible to perform boosts of the particles correctly if the boost parameters are 
large (in certain of the events where errors occurred, we found, for instance, a pion with 
momentum of order of TeV/c). 

A special routine PHCORK, which corrects these kinds of inconsistencies, have been 
developed and inserted to PHOTOS code 2 . 

The routine works in one of four modes, selected at the initialization of PHOTOS: 

• mode 1: no correction performed, 

• mode 2: energy is corrected from mass, 

2 This routine became available in 1999 and can be found in the CERNLIB version of PHOTOS. 
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• mode 3: mass is corrected from energy, 



• mode 4: energy is corrected from mass for particles up to a mass of 0.4 GeV, for 
heavier ones: mass is corrected. 

In cases, where a branch (sub-cascade starting from certain particles) has two mothers, 
the first mother's momentum is corrected according to the sum of its children momenta 
and the momentum of the second mother. 

The default mode is 1, which means that no correction is applied, and full compatibility 
with older implementations is retained. 

Correction is performed in two steps. First, all daughters' energies (or masses, de- 
pending on the requested mode of correction) are corrected to fulfil the E 2 — p 2 = M 2 
constraint. 

In the second step, the sum of all daughters' 4-momenta is calculated. The mother's 
momentum is corrected to this value. In cases where two mothers are present, only the 
first mother's 4-momentum is corrected to a value: 



7.2.2 Interference correction 

In the published version of PHOTOS [2j the interference between photon emission from two 
sources was available only for two-body decays into particles of opposite charge and equal 
mass. Since then, the interference correction was extended to work also in the case of 
decays into particles of distinct masses. On the technical side the interference correction 
was re-coded to work more efficiently. For example this should prevent the program to 
stop in case of double bremsstrahlung and interference corrections in the decay of the 
very heavy Z/j* — > e + e~ state. 

7.2.3 Enabling flags 

For some users, it is convenient to block/enable PHOTOS generation in some cases, for 
tests or because of unphysical coding of events into the HEPEVT common block. Flags 
to block/enable PHOTOS generation in tt° — > e + e~7 and in W decay into quarks were 
introduced. The flags are initialized in the subroutine PHOINI. 

7.2.4 Weight correction in the decay W — > lv\ 

For the leptonic decays of the W boson, PHOTOS predictions were carefully compared 
with the results from the first order matrix element generator [3*2"] . It was found that 
even though the leading corrections were properly modelled by PHOTOS, the non-leading 
missing effects were relatively large. The origin of these discrepancies was understood, 
and the appropriate correcting weight was introduced into PHOTOS. With these changes 
the agreement with the matrix element calculation improved sizeably , especially in 
regions of phase space populated with hard non-collinear photons. A new option was 
introduced, to initialize this correcting weight. It can be switched on/off with the new 
flag IFW, initialized in subroutine PHOCIN. The method can easily be extended to other 
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processes where the matrix element is available from QED calculations or from modelling 
based on experimental data. 

7.2.5 PHOTOS 2.07 

Once all these modifications are installed, the new version 2.07 of PHOTOS was created. 

8 Issues related to distinct event record schemes 

Let us note that the packages presented here work with the standard HEPEVT event record, 
where the tree structure of the event evolution is properly coded into a unique tree 
structure. Generally this is not the case. However, the programs were shown to work 
properly with the extension of the standard of the type as originating from PYTHIA j^UJ 
with MSTP(128)=0, 1 ,2. Necessary adjustments turned out to be non-trivial and in fact 
correctness of their action cannot be garanteed in the general case jHj. The case of 
HERWIG j2Bj turned out to be even more complex. Even though in this case the HEPEVT 
common block is used as standard event record, the mother-daugter pointers are nonethe- 
less used in a different way. As a consequence, events generated by HERWIG are far from 
the design format of the HEPEVT event record. We were able to tune the working of the 
TAUOLA universal interface to the requirements of operating with HERWIG; however, 
the interfacing of PHOTOS turned out to be rather more difficult. 

The principal issue from which difficulties with the HEPEVT decoding arise is that 
PYTHIA as well as HERWIG produce a new copy of the participating particles each time a 
physical effect (e.g. final state radiation) is added; consequently several copies of particle 
entries are produced, which cannot be consistently put in the HEPEVT structure. In order 
to circumvent this problem, the JMOHEP and/or JDAHEP entries are overloaded, i.e. the 
information stored in them is used for other purposes than their original one. For example, 
PYTHIA with MSTP(128)=0 setting uses the JMOHEP entry to point to the copies of a particle 
(cf. Fig. EJ) and HERWIG uses the JMOHEP (2, 1) entries to store the colour information of 
the particle flow. A generic interface thus has to be informed of these possibilities and to 
correct for them for the TAUOLA and PHOTOS procedures to work properly. 

At present a working version of modified PHOTOS routines, which appears to work with 
HERWIG, can be found in the distribution of AcerMC [21]. However rigorous testing is 
necessary before these modifications can be included in the official PHOTOS distribution. 
The original PHOTOS code had to be modified due to the 'overloaded' HEPEVT record, since 
its requirements for matching mother-daughter pointers were too strict for either PYTHIA 
or HERWIG. The modification was limited to PH0T0S_MAKE and PH0B0S routines. In addition 
the tracking of the IDHW array was added to PH0T0S_MAKE to accommodate the HERWIG 
event record. A further modification was however necessary in the PHOIN routine since 
in HERWIG the entry JMOHEP (2, 1) is not empty but filled with colour flow information, 
which in turn inhibited PHOTOS radiation off participating particles 3 

3 PH0T0S expects the non-zero second mother JMOHEP (2, 1) entry only for gg(qq) — > tt process, which 
is treated by a set of dedicated routines; this in turn clashes with HERWIG overloaded JMOHEP (2, 1) entry. 
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Figure 3: The usage of JMOHEP and JDAHEP pointers in PYTHIA with MSTP(128)=0 setting. 
While PYTHIA keeps the JDAHEP entries to point in the direction of event evolution, the 
JMOHEP is used to point to the copies of a particle produced when perturbative effects, 
such as initial state radiation(ISR) or r decays are added; the particle copies at different 
stages of event simulation are consistently distinguished by the ISTHEP tags. 
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It has to be stressed that implementing the HERWIG interface to PHOTOS is desirable 
since up to version 6.5 HERWIG did not have any QED radiation implemented in the decays. 
In the later releases, PHOTOS is installed in decays (and hadronic production) of t-quarks, 
as well as in W decays. This is done, however, through specifically tailored interfaces 
embodied within the HERWIG code. 

Another two issues are related to the double counting. If there is no information passed 
from the host program and the common block PHOQED of PHOTOS is not appropriately 
filled, then there is no way for PHOTOS to know that in some decays it should not generate 
bremsstrahlung (again) and thus 'double counting' will appear. While the question is 
not relevant for HERWIG, since no photon bremsstrahlung is implemented, it can become 
an issue in PYTHIA, for some specific processes. Indeed, one can generally switch off the 
photon radiation off leptons (by setting a high limit on PARJ(90), cf. (ID]); however, one 
cannot do it on the basis of specific processes and/or decays. 

The issue is not shared in the TAUOLA universal interface, since the decayed r 
leptons are not decayed again and the original decay will remain. 

9 Summary and future possibilities 

We have presented the system for creating the required version of PHOTOS and TAUOLA 
packages from their master versions. The master versions are structured in a relatively 
compact form without code duplications etc. The minor modifications of the programs, 
introduced since their publication, were also explained. 

The creation of the system was the first step towards future attempts to develop pack- 
ages without loss of their present physics contents. Some experience, already collected in 
that direction, is summarized in [3H]. We find the question of the language translation 
for the fixed program version relatively easy. On the contrary, the question of project 
continuity into further upgrades motivated by the physics needs to be thought over care- 
fully. Matching the programming styles of the C++ experts with the strategies of testing 
numerical correctness of consecutive versions is a rather crucial issue, which has to be 
addressed. Tools and methods embodied in Fortran code survive such translation with 
difficulty 

At a certain moment, the necessary strategy may thus require fluency in the For- 
tran, Object-Orientated languages and physics content of the project by the same person. 
Platform-independent tools for mixing code in Fortran and 00 languages might be of 
great help. 

In this paper we have also documented for the first time technical side of the universal 
interface for the TAUOLA package. From now on, its version number 1.10 is printed in the 
output. 
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